{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9464f3ea",
   "metadata": {},
   "source": [
    "# Introduction to Airweave\n",
    "\n",
    "Airweave is an open-source platform enables AI agents to search your data sources, like business apps and databases. \n",
    "Airweave does this by turning them into queryable knowledge bases for AI agents. \n",
    "\n",
    "This quickstart guide will walk you through the essential steps to get started with Airweave using the Python SDK. We also have an SDK for Node.js. Check it out by heading over to https://docs.airweave.ai/quickstart\n",
    "\n",
    "### What you'll learn in this notebook\n",
    "In this tutorial, you'll learn how to:\n",
    "- Set up the Airweave Python client\n",
    "- Create a collection to organize your data sources\n",
    "- Connect data sources to your collection\n",
    "- Search across all connected sources with natural language queries\n",
    "\n",
    "### Prerequisites\n",
    "Before starting, make sure you have:\n",
    "- Python 3.11 or higher installed\n",
    "- An Airweave API key (get one from https://app.airweave.ai or your local instance)\n",
    "- Access to at least one data source (we'll use Stripe account with test data as an example)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff50be16",
   "metadata": {},
   "source": [
    "## Step 1: Installation and Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "886011f2",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: airweave-sdk in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (0.6.14)\n",
      "Requirement already satisfied: httpx>=0.21.2 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from airweave-sdk) (0.28.1)\n",
      "Requirement already satisfied: pydantic>=1.9.2 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from airweave-sdk) (2.11.9)\n",
      "Requirement already satisfied: pydantic-core>=2.18.2 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from airweave-sdk) (2.33.2)\n",
      "Requirement already satisfied: typing_extensions>=4.0.0 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from airweave-sdk) (4.15.0)\n",
      "Requirement already satisfied: anyio in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from httpx>=0.21.2->airweave-sdk) (4.11.0)\n",
      "Requirement already satisfied: certifi in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from httpx>=0.21.2->airweave-sdk) (2025.8.3)\n",
      "Requirement already satisfied: httpcore==1.* in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from httpx>=0.21.2->airweave-sdk) (1.0.9)\n",
      "Requirement already satisfied: idna in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from httpx>=0.21.2->airweave-sdk) (3.10)\n",
      "Requirement already satisfied: h11>=0.16 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from httpcore==1.*->httpx>=0.21.2->airweave-sdk) (0.16.0)\n",
      "Requirement already satisfied: annotated-types>=0.6.0 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from pydantic>=1.9.2->airweave-sdk) (0.7.0)\n",
      "Requirement already satisfied: typing-inspection>=0.4.0 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from pydantic>=1.9.2->airweave-sdk) (0.4.1)\n",
      "Requirement already satisfied: sniffio>=1.1 in /Users/lennertjansen/Documents/code/airweave-ai/airweave/backend/venv/lib/python3.11/site-packages (from anyio->httpx>=0.21.2->airweave-sdk) (1.3.1)\n",
      "\n",
      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m A new release of pip is available: \u001b[0m\u001b[31;49m24.3.1\u001b[0m\u001b[39;49m -> \u001b[0m\u001b[32;49m25.2\u001b[0m\n",
      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m To update, run: \u001b[0m\u001b[32;49mpip install --upgrade pip\u001b[0m\n",
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "# First, pip install the Airweave SDK (run this once):\n",
    "%pip install airweave-sdk"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90c3ff1c",
   "metadata": {},
   "source": [
    "Once installed, import the SDK and initialize the client with your API key. Find it on app.airweave.ai \n",
    "or in the dashboard of your locally running instance.\n",
    "If you're running Airweave locally, change the base_url to \"http://localhost:8001\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f78d1f2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "from airweave import AirweaveSDK\n",
    "\n",
    "# Initialize the Airweave client\n",
    "client = AirweaveSDK(\n",
    "    api_key=\"YOUR_API_KEY\",  # Get your actual API key from the Airweave dashboard\n",
    "    base_url=\"https://api.airweave.ai\",  # Use \"http://localhost:8001\" for local deployment\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64ae95ae",
   "metadata": {},
   "source": [
    "## Step 2: Create a collection\n",
    "\n",
    "A collection in Airweave is a searchable container that groups user-specified data sources together.\n",
    "Think of it as a unified search index that can query multiple data sources\n",
    "simultaneously. For example, you might create a \"Customer Data\" collection\n",
    "that includes data from Stripe, HubSpot, and your internal Postgres database, or a \"Productivity Tools\" collection \n",
    "containing your Notion, Linear, and Microsoft Teams accounts.\n",
    "\n",
    "You are free to add as many or as little sources to a collection as you like. The important thing to remember is that, in Airweave, a collection is what's being searched by an agent.\n",
    "\n",
    "Let's create your first collection:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "388cc35e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "✅ Created collection: my-first-collection-ezhgns\n",
      "   Name: My First Collection\n",
      "   ID: YOUR_COLLECTION_ID\n"
     ]
    }
   ],
   "source": [
    "# Create a new collection\n",
    "collection = client.collections.create(\n",
    "    name=\"My First Collection\"  # Give your collection a descriptive name\n",
    ")\n",
    "\n",
    "print(f\"✅ Created collection: {collection.readable_id}\")\n",
    "print(f\"   Name: {collection.name}\")\n",
    "print(f\"   ID: {collection.id}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "424aadae",
   "metadata": {},
   "source": [
    "The collection has been created with:\n",
    "- a unique readable_id that you'll use to reference it in future operations,\n",
    "- a name that you can change at any time,\n",
    "- and a randomly generated version-4 UUID.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ffd57fc",
   "metadata": {},
   "source": [
    "## Step 3: Add a source connection\n",
    "\n",
    "Now that we have a collection, let's connect a data source to it.\n",
    "Source connections handle authentication and automatically sync data from\n",
    "your apps and databases into Airweave.\n",
    "\n",
    "Airweave supports numerous integrations including:\n",
    "- Business apps like Stripe, GitHub, HubSpot, Notion, Gmail, Linear, etc.\n",
    "- Document stores like Dropbox, Google Drive, and OneDrive\n",
    "- Databases like PostgreSQL\n",
    "\n",
    "In this example, we'll connect to Stripe, but the process is similar for\n",
    "other data sources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d49109d1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "✅ Created source connection: My Stripe Connection\n",
      "   Status: active\n",
      "   Type: stripe\n"
     ]
    }
   ],
   "source": [
    "# Create a source connection to Stripe\n",
    "# You'll need to replace 'your_stripe_api_key' with an actual Stripe API key\n",
    "source_connection = client.source_connections.create(\n",
    "    name=\"My Stripe Connection\",  # A name for this connection\n",
    "    short_name=\"stripe\",  # The connector type (e.g., 'stripe', 'hubspot', 'postgresql')\n",
    "    readable_collection_id=collection.readable_id,  # Link to our collection\n",
    "    authentication={\n",
    "        \"credentials\": {\n",
    "            \"api_key\": \"sk_YOUR_STRIPE_API_KEY\"  # Replace with real API key\n",
    "        }\n",
    "    }\n",
    ")\n",
    "\n",
    "print(f\"✅ Created source connection: {source_connection.name}\")\n",
    "print(f\"   Status: {source_connection.status}\")\n",
    "print(f\"   Type: {source_connection.short_name}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7275c86a",
   "metadata": {},
   "source": [
    "Once source connection is established, Airweave will automatically:\n",
    "1. Validate the credentials\n",
    "2. Begin syncing data from Stripe\n",
    "3. Extract and index relevant entities (customers, payments, invoices, etc.)\n",
    "4. Make the data searchable through natural language queries\n",
    "\n",
    "The initial sync may take a few minutes depending on the amount of data.\n",
    "You can check the sync status through the dashboard or API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e7de55a",
   "metadata": {},
   "source": [
    "## Step 4: Search your collection\n",
    "\n",
    "With your data sources connected and synced, you or your agent can now search across all the data in the collection, using just natural\n",
    "language queries. \n",
    "\n",
    "Airweave uses advanced semantic search to understand the intent of your queries and return relevant results.\n",
    "\n",
    "Let's try some example searches:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d26eb79",
   "metadata": {},
   "source": [
    "### Example: Search for specific customer information in Stripe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "6f73cabc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "🔍 Searching for customer payment information...\n",
      "\n",
      "📍 Result 1 (Score: 88.83%)\n",
      "   Source: stripe | Type: StripePaymentIntentEntity\n",
      "   ID: pi_3Q13xgGm1FpXlyE50uRm1zO2\n",
      "   Amount: 1008\n",
      "   Currency: eur\n",
      "   Status: canceled\n",
      "   Description: Dua Lipa Concert ticket 2025\n",
      "   Created At: 2024-09-20T10:21:16+00:00\n",
      "   Customer Id: cus_QpEel2ZOt74xmy\n",
      "------------------------------------------------------------\n",
      "\n",
      "📍 Result 2 (Score: 51.82%)\n",
      "   Source: stripe | Type: StripePaymentIntentEntity\n",
      "   ID: pi_3Q17MZGm1FpXlyE51ZMPa9cr\n",
      "   Amount: 1008\n",
      "   Currency: eur\n",
      "   Status: canceled\n",
      "   Description: Dua Lipa Concert ticket 2025\n",
      "   Created At: 2024-09-20T13:59:11+00:00\n",
      "   Customer Id: cus_QpEel2ZOt74xmy\n",
      "------------------------------------------------------------\n",
      "\n",
      "📍 Result 3 (Score: 47.38%)\n",
      "   Source: stripe | Type: StripePaymentIntentEntity\n",
      "   ID: pi_3Q1373Gm1FpXlyE5195Woh3n\n",
      "   Amount: 1008\n",
      "   Currency: eur\n",
      "   Status: canceled\n",
      "   Description: Dua Lipa Concert ticket 2025\n",
      "   Created At: 2024-09-20T09:26:53+00:00\n",
      "   Customer Id: cus_QpEel2ZOt74xmy\n",
      "------------------------------------------------------------\n",
      "\n",
      "📍 Result 4 (Score: 39.98%)\n",
      "   Source: stripe | Type: StripePaymentIntentEntity\n",
      "   ID: pi_3Q17TsGm1FpXlyE51wWVduuC\n",
      "   Amount: 1008\n",
      "   Currency: eur\n",
      "   Status: canceled\n",
      "   Description: Dua Lipa Concert ticket 2025\n",
      "   Created At: 2024-09-20T14:06:44+00:00\n",
      "   Customer Id: cus_QpEel2ZOt74xmy\n",
      "------------------------------------------------------------\n",
      "\n",
      "📍 Result 5 (Score: 16.77%)\n",
      "   Source: stripe | Type: StripePaymentIntentEntity\n",
      "   ID: pi_3PxrxGGm1FpXlyE50SnwWx4E\n",
      "   Amount: 1005\n",
      "   Currency: eur\n",
      "   Status: canceled\n",
      "   Description: Ticket bought from Rauf Akdemir\n",
      "   Created At: 2024-09-11T14:55:38+00:00\n",
      "   Customer Id: cus_QpEel2ZOt74xmy\n",
      "------------------------------------------------------------\n",
      "\n",
      "📍 Result 6 (Score: 14.32%)\n",
      "   Source: stripe | Type: StripePaymentIntentEntity\n",
      "   ID: pi_3PxsZsGm1FpXlyE51G6Hk74K\n",
      "   Amount: 1008\n",
      "   Currency: eur\n",
      "   Status: canceled\n",
      "   Description: Rauf's Taylor Swift Ticket.\n",
      "   Created At: 2024-09-11T15:35:32+00:00\n",
      "   Customer Id: cus_QpEel2ZOt74xmy\n",
      "------------------------------------------------------------\n"
     ]
    }
   ],
   "source": [
    "print(\"\\n🔍 Searching for customer payment information...\")\n",
    "results = client.collections.search(\n",
    "    readable_id=collection.readable_id, query=\"Payment attempts for concert tickets\"\n",
    ")\n",
    "\n",
    "# Display the search results\n",
    "for i, result in enumerate(results.results[:6], 1):  # Show first 6 results\n",
    "    score = result.get('score', 0)\n",
    "    payload = result.get('payload', {})\n",
    "    \n",
    "    # Extract common fields that exist across different sources\n",
    "    entity_id = payload.get('entity_id', 'N/A')\n",
    "    source = payload.get('airweave_system_metadata', {}).get('source_name', 'Unknown')\n",
    "    entity_type = payload.get('airweave_system_metadata', {}).get('entity_type', 'Unknown')\n",
    "    \n",
    "    print(f\"\\n📍 Result {i} (Score: {score:.2%})\")\n",
    "    print(f\"   Source: {source} | Type: {entity_type}\")\n",
    "    print(f\"   ID: {entity_id}\")\n",
    "    \n",
    "    # Display other fields dynamically (excluding metadata)\n",
    "    for key, value in payload.items():\n",
    "        if key not in ['entity_id', 'airweave_system_metadata', 'breadcrumbs', 'metadata']:\n",
    "            if value is not None and value != '':\n",
    "                print(f\"   {key.replace('_', ' ').title()}: {value}\")\n",
    "    \n",
    "    print(\"-\" * 60)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d71c3526",
   "metadata": {},
   "source": [
    "And there you have it, the search results include:\n",
    "- Relevant entities from your connected sources\n",
    "- Confidence scores indicating relevance\n",
    "- Metadata about the source and entity type\n",
    "- The actual content that matches your query"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f7fcaa93",
   "metadata": {},
   "source": [
    "## Congratulations! 🎉\n",
    "\n",
    "You've successfully:\n",
    "- ✅ Set up the Airweave Python client\n",
    "- ✅ Created a collection\n",
    "- ✅ Connected data sources\n",
    "- ✅ Performed searches across your data\n",
    "\n",
    "### What's Next?\n",
    "\n",
    "#### Explore More Integrations\n",
    "- Check out the full list of available connectors and [search functionality](https://docs.airweave.ai/search) in the [documentation](https://docs.airweave.ai/welcome) and connect more of your data sources.\n",
    "- Consider becoming a contributor and [adding a custom connector](https://docs.airweave.ai/add-new-source)\n",
    "\n",
    "\n",
    "#### Join the Community\n",
    "- GitHub: https://github.com/airweave-ai/airweave\n",
    "- Discord: https://discord.gg/484HY9Ehxt\n",
    "- Documentation: https://docs.airweave.ai"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
